Release notes 2025
2025r6
Secondary time allocations in commercial API
From this version, it is possible to include secondary time allocations when publishing an interstitial schedule to an external system. That system can use the commercial API to retrieve the schedule via the interstitial schedule outbox and send updates back to Mediagenix Base. Therefore, the commercial API has been adapted to support secondary time allocations.
GET /breakSchedule call
This call returns all transmissions and its time allocations for a specified broadcast day based on the interstitial schedule outbox that was last published.
If secondary time allocations were also exported, the response of the GET /breakSchedules call returns them as well with the same attributes as the regular time allocations. Note that the title of secondary time allocations will be based on the title of the time allocation type, which can be seen in the calculated title of the STA in the secondary time allocation assistant.
The Time allocation kind property has been added as the kind attribute to the properties of the time allocation. Even when there are no secondary time allocations in the response, the kind attribute is present.
The time allocations in the timeAllocations array are now sorted on startTime and then by the kind, instead of OID. This means that if a primary time allocation and a secondary time allocation start at the same time, the primary time allocation is listed first.
For example, the timeAllocations array of the call:
"timeAllocations": [
{
"breakId": "string",
"externalBreakId": "string",
"startTime": "14:15:00",
"startTimeUTC": "13:15:00",
"duration": "00:05:00",
"kind": "Primary"
"type": "Commercial break, promotion, sponsorship,...",
"readOnly": false,
"title": "string",
"sequenceNumber": 0,
"position": "Start",
"regional": true,
"masterBreakId": "string",
...
},
{
"breakId": "string",
"externalBreakId": "string",
"startTime": "14:15:00",
"startTimeUTC": "13:15:00",
"duration": "00:05:00",
"kind": "Secondary"
"type": "Commercial break, promotion, sponsorship,...",
"readOnly": false,
"title": "string",
"sequenceNumber": 0,
"position": "Start",
"regional": true,
"masterBreakId": "string",
...
},POST /commercialPlaylist
This call allows to send the time allocations, transmission events and commercials with media assets that should be used to fill the broadcast day. They will be created as interstitial blocks and clips for the interstitial integration.
This call can now create interstitial blocks and clips for secondary time allocations as well. The kind attribute has also been added to the timeAllocations array of the body of the call to be able to assign a type to the interstitial block, so it is easier for matching:
{
...
"timeAllocations": [
{
"breakId": "string",
"externalBreakId": "string",
"startTime": "14:15:00",
"startTimeUTC": "13:15:00",
"kind": "Primary",
"type": "Commercial break",
"title": "string",
"remarks": "string",
"events": [
...When the attribute is not included in the call, the kind of the interstitial block will be empty. It is not mandatory because it is more for informational purposes and can still be overruled when matching.
When a time allocation with kind Secondary is sent for a certain time allocation type, but the Include secondary time allocations column of the interstitial integration is set to No for that type, a 422 error is returned with the following message:
{
"statusCode": "422",
"message": "Operation cannot be completed due to violations",
"timestamp": "2025-05-19T08:15:32Z",
"concept": "Commercial playlist",
"id": null,
"errors": [
{
"errorCode": "COMMERCIAL-00015",
"description": "Secondary time allocations are not included in the block definition for type commercial.",
"data": [
"commercial"
]
}
]
}This check is done after the check for COMMERCIAL-00010, which checks if the time allocation type that is provided is part of the interstitial integration definition. This message has been renamed for clarity from Time allocation block defnition not found to No block definitions exist for the provided time allocation type.
PUT /commercialBreak
This call updates the interstitial blocks and clips for the specified time allocations and can only be executed after a POST /commercialPlaylist call has been done first. It uses the same properties as the POST /commercialPlaylist call, so it has the same changes as above.
PUT /commercialBreakDuration
This call allows to update the duration of the time allocations in the schedule and can now update secondary time allocations as well by providing their breakLabel or externalBreakId.
It does not update or create the interstitial inbox but directly impacts the time allocation itself, so the kind attribute was not added here. The checks described for the PUT and POST call are also not done when using this call.
API developers
The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.
At line 677, the kind was added to the properties of the time allocations in the BreakSchedule schema.
At line 924, the kind was added to the properties of the TimeAllocationForPlaylist schema.
For easier viewing, the YAMLs can also be compared here: TextCompare
2025r5
Fix for transmissions under embargo
When a transmission is marked as under embargo, certain product attributes are returned as null. Previously, the txTitle attribute in the commercial API was still returned even when the transmission was under embargo. This issue has been fixed in this version.
2025r4
Prevent or allow update of media assets using commercial API
In a previous version, it became possible to update media assets using the commercial API. However, this caused the API to become backwards incompatible.
From this version, by default, it is not possible anymore to update media assets using the API, but only create them. When using the POST /commercialPlaylist, POST /commercial and PUT /commercialBreak calls, it is checked if the media asset referenced in the mediaAssetId already exists:
-
If so, the media asset information in the payload is ignored, and the BAPI service will log: Media asset information was ignored. The commercial API can only create media assets.
-
If it does not exist, the media asset is created.
We would recommend not changing this behaviour; however, if this is absolutely required, an option can be activated to allow updating. Contact Mediagenix to activate this for you.
Drop-down list call for target groups of predicted ratings in commercial API
In a previous version, the predictedRatings array was added to the GET /breakSchedules of the commercial API. The YAML mentioned that the values of the targetGroup attribute could be retrieved with the GET /targetGroups call. However, this call was not part of the API.
From this version, the GET /targetGroups call has been added to the commercial API.
When the call is sent, it returns the API references and descriptions of the values of the TMCampaignTargetGroup drop-down list.
[
{
"id": "Adults",
"name": "Adults"
},
{
"id": "Kids",
"name": "Kids"
},
{
"id": "Teens",
"name": "Teens"
},
{
"id": "60+",
"name": "60+"
}
]It can already be used, but will be added to the YAML in a future version.
Transmission title added to commercial API YAML
This information is mostly relevant for API developers.
In the previous version, the txTitle attribute was added to the GET /breakSchedule call of the commercial API, but it was not yet added to the YAML.
In this version, the txTitle was added to the properties of the Transmission schema of the YAML at line 734. The latest version can be retrieved by using the GET /api call.
2025r3
Transmission title in GET /breakSchedule call of commercial API
The commercial API contains a GET /breakSchedule call, which is used by the external system after publishing an interstitial schedule for interstitial integration. The call retrieves all transmissions and time allocations of the type specified in the interstitial integration definition for a channel on a specific date.
Previously, the transmissions array contained the productTitle and the seriesTitle, but not the title of the transmission itself, which can be different.
From this version, the txTitle attribute has been added to the response body of the GET /breakSchedule call. It maps to the head title of the transmission.
An example of the response:
{
"channelId": "MGX",
"startDate": "2025-11-01",
"scheduleVersion": "Active",
"dayStatus": "closed",
"definitionId": "Comm",
"transmissions": [
{
"transmissionId": "9501555641",
"startTime": "09:33:00",
"startTimeUTC": "08:33:00",
"announcedStartTime": "09:25",
"lockedStartTime": false,
"duration": "01:28:30",
"productId": "9501369293",
"parentalRating": null,
"txTitle": "FFG 2024 - Presence",
"productType": "program",
"productCode": null,
"productTitle": "Presence",
"seriesTitle": null,
...
"timeAllocations": [
{
"breakId": "000025",
"externalBreakId": null,
"startTime": "10:03:30",
"duration": "00:01:00",
"type": "commercial",
"position": "Middle",
"startTimeUTC": "09:03:30",
"readOnly": false,
"title": "Presence - - Commercial",
"sequenceNumber": 4,
"regional": false,
"masterBreakId": null,
"predictedRatings": []
}
]
}
]
}